<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>getcontext</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_479">&nbsp;</a>NAME</h4><blockquote>
getcontext, setcontext - get and set current user context
</blockquote><h4><a name = "tag_000_005_480">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="ucontext.h.html">ucontext.h</a>&gt;

int getcontext(ucontext_t *<i>ucp</i>);
int setcontext(const ucontext_t *<i>ucp</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_481">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>getcontext()</i>
function initialises the structure pointed to by <i>ucp</i> to the current user
context of the calling thread.  The
<b>ucontext_t</b>
type that <i>ucp</i>
points to defines the user context and includes the contents of the calling
thread's machine registers, the signal mask, and the current execution stack.
<p>
The
<i><a href="setcontext.html">setcontext()</a></i>
function restores the user context pointed to by <i>ucp</i>.  A successful
call to
<i><a href="setcontext.html">setcontext()</a></i>
does not return; program execution resumes at the point
specified by the <i>ucp</i> argument passed to
<i><a href="setcontext.html">setcontext()</a></i>.
The <i>ucp</i> argument should be created either by a prior call to
<i>getcontext()</i>
or
<i><a href="makecontext.html">makecontext()</a></i>,
or by being passed as an argument to a signal handler.
If the <i>ucp</i> argument was created with
<i>getcontext()</i>,
program execution continues as if the corresponding call of
<i>getcontext()</i>
had just returned.  If the <i>ucp</i> argument was created with
<i><a href="makecontext.html">makecontext()</a></i>,
program execution continues with the function passed to
<i><a href="makecontext.html">makecontext()</a></i>.
When that function returns, the thread continues as if after a call to
<i><a href="setcontext.html">setcontext()</a></i>
with the <i>ucp</i> argument that was input to
<i><a href="makecontext.html">makecontext()</a></i>.
If the <b>uc_link</b> member of the
<b>ucontext_t</b>
structure pointed to by the <i>ucp</i>
argument is equal to 0, then this context is the main context, and the thread
will exit when this context returns.  The effects of passing a <i>ucp</i>
argument obtained from any other source are unspecified.
</blockquote><h4><a name = "tag_000_005_482">&nbsp;</a>RETURN VALUE</h4><blockquote>
On successful completion,
<i><a href="setcontext.html">setcontext()</a></i>
does not return and
<i>getcontext()</i>
returns 0.
Otherwise, a value
of -1 is returned.
</blockquote><h4><a name = "tag_000_005_483">&nbsp;</a>ERRORS</h4><blockquote>
No errors are defined.
</blockquote><h4><a name = "tag_000_005_484">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_485">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
When a signal handler is executed, the current user context is saved and a new
context is created.  If the thread leaves the signal handler via
<i><a href="longjmp.html">longjmp()</a></i>,
then it is unspecified whether the context at the time of the corresponding
<i><a href="setjmp.html">setjmp()</a></i>
call is restored and thus whether future calls to
<i>getcontext()</i>
will provide an accurate representation of the current context, since the
context restored by
<i><a href="longjmp.html">longjmp()</a></i>
does not necessarily contain all the information that
<i><a href="setcontext.html">setcontext()</a></i>
requires.  Signal handlers should use
<i><a href="siglongjmp.html">siglongjmp()</a></i>
or
<i><a href="setcontext.html">setcontext()</a></i>
instead.
<p>
Portable applications should not modify or access the <b>uc_mcontext</b>
member of <b>ucontext_t</b>.  A portable application cannot assume that context
includes any process-wide static data, possibly including
<i>errno</i>.
Users manipulating contexts should take care to handle these explicitly when
required.
<p>
Use of contexts to create alternate stacks is not defined by this
specification.
</blockquote><h4><a name = "tag_000_005_486">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_487">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="bsd_signal.html">bsd_signal()</a></i>,
<i><a href="makecontext.html">makecontext()</a></i>,
<i><a href="setjmp.html">setjmp()</a></i>,
<i><a href="sigaction.html">sigaction()</a></i>,
<i><a href="sigaltstack.html">sigaltstack()</a></i>,
<i><a href="sigprocmask.html">sigprocmask()</a></i>,
<i><a href="sigsetjmp.html">sigsetjmp()</a></i>,
<i><a href="ucontext.h.html">&lt;ucontext.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
